home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
The X-Philes (2nd Revision)
/
The X-Philes Number 1 (1995).iso
/
xphiles
/
hp48_2
/
tools.exe
/
DOCS
/
USRLIB.DOC
< prev
Wrap
Text File
|
1991-07-19
|
24KB
|
728 lines
Instructions for MS-DOS program "USRLIB"
*****************************************************************
NOTICE
Hewlett-Packard is making the current preliminary version 2.2 of
USRLIB.EXE available to customers free of charge to help them in
HP 48SX application development, under the following conditions:
* The program USRLIB.EXE and the documentation file USRLIB.MAN are
provided "as is," and are subject to change without notice.
Hewlett-Packard Company make no warranty of any kind with regard
to the software or documentation, including, but not limited to,
the implied warranties of merchantability and fitness for a
particular purpose. Hewlett-Packard Company shall not be liable
for any error or for incidental or consequential damages in
connection with the furnishing, performance, or use of this
software and documentation.
* The program and documentation are copyrighted by Hewlett-
Packard. Customers may freely reproduce and distribute this
material. Sale of this material is prohibited without prior
written permission of Hewlett-Packard Company.
* The HP Customer Support department does not support the current
version. Questions, comments, defect reports, etc. should be
directed to the Library Development conference on the HP
Calculator Bulletin Board System. All responses from Hewlett-
Packard will normally be provided through that conference.
* Software converted into libraries by USRLIB.EXE should be tested
and qualified in its library form. Discrepancies between the
execution of the libraries and the execution of the original
source directory contents should be reported via the Bulletin
Board.
Revised versions of the software and documentation will be posted
on the Bulletin Board as they become available. In particular,
future versions will include less cryptic error messages, and
better documention of the output listing information provided by
the program.
Version 2.2 of the program USRLIB.EXE is a preliminary version of
this software. Software compiled into libraries using this
program should be thoroughly tested in its library form prior to
any reproduction or distribution to end users.
*****************************************************************
-1-
1. INTRODUCTION
USRLIB.EXE is an MS-DOS executable file that creates an HP 48
library object from an HP 48 directory. A library is similar to a
directory in that both are collections of named objects. However,
a directory normally resides in main RAM memory and is intended
for continuous modification and execution, whereas a library
contains objects intended for execution only, and can be used from
ROM as readily as from RAM. A directory's objects are organized
in a linked list requiring a sequential search for access; a
library contains an address table that provides rapid execution
access to its individual objects.
1.1 Glossary of Terms
Directory HP48 directory object containing zero or more
variables.
Variable A named object contained within a directory,
accessed by means of a global name.
Library HP 48 library object containing zero or more
library commands. Libraries include a text
title, a Library ID number, and optional
message tables and configuration code that is
executed at system halts.
Library command A named object within a library, which is the
library analog of a directory's variable.
Global name HP 48 global name object, execution of which
executes the object in the corresponding
(global) variable.
XLIB name HP 48 XLIB name object, execution of which
executes the corresponding library command.
An XLIB name plays the role for libraries that
a global name plays for directories.
Library ID A number in the range 0-7FFh that uniquely
identifies a library, and is used as an
argument for HP 48 commands that deal with
libraries as objects. The following ranges
are defined for the ID numbers:
-2-
ID Range Purpose
Hex Decimal
0 - 100 0 - 256
101 - 200 257 - 512 HP ROM-Based Applications
201 - 300 513 - 768 HP RAM-Based Applications
301 - 600 769 - 1536
Non-HP Applications
(numbers permanently
assigned by HP)
601 - 6FF 1537 - 1792
700 - 7FF 1792 - 2047 HP 48SX Command Line Use
1.2 The Source Directory
USRLIB uses an HP 48 directory object as the source file to define
the output library. The source directory may contain any number
of variables, each of which is converted to a library command in
the output library (unless specified otherwise; see $VARS,
$VISIBLE and $HIDDEN, below). The objects in the variables are
translated as necessary so that any global names in the objects
that correspond to variables in the source directory are converted
to XLIB names.
The source directory may contain subdirectories, but in that case
the resulting library will not reflect the structure of the
directory since a library structure is "flat." If separate
subdirectories contain variables with the same name, the uses of
those names within the library will be correct, but the duplicated
names will also be duplicated in the LIBRARY menu. The names of
the subdirectories themselves are not translated to library
commands, and any use of those names in any of the other variables
will result in an error during execution of USRLIB.
The directory may also include the following special variables:
$ROMID Contains a real or binary number object representing
the Library ID that is to be given to the library.
This can be overridden by specifying -rrrrroooommmmiiiidddd on the
command line. The ID should be in the range 769 -
1792 (301h - 6FFh).
The -r option must be specified from the command line
if no $ROMID is used.
$TITLE Contains a string to be used as the name of the
library. This can be overridden by specifying -tttttiiiittttlllleeee
on the command line. The first (up to) 5 characters
of the title are used for the LIBRARY menu label; the
-3-
first 22 characters are displayed by REVIEW.
$CONFIG Contains an object to be executed at configuration
time. If no $CONFIG variable is present, no
configuration entry will be generated. In the current
version of USRLIB, $CONFIG is also translated to a
library command; to prevent this, it $CONFIG should be
declared as hidden (see below).
Note: the configuration code can generally NOT be
written in user-accessible commands. Simple programs
such as << 123 ATTACH >> are OK, but more complicated
programs should take care to leave the stack
unchanged, and be sure NOT TO ERROR.
$MESSAGE Contains a list of names of variables that contain
strings to be combined into a message table. The
message numbers correspond to the list positions.
If no $MESSAGE is present, no message table will be
generated.
$VISIBLE Contains a list of names of variables to be converted
to user-accessible library commands.
By default, all variables will be translated to
library commands. When the $VISIBLE list is present,
only the names in this list are used as XLIB name
table entries in the library. An empty list is
allowed, meaning that no XLIB name entries are
created.
$HIDDEN Contains a list of names of variables that are to be
converted to null-named objects in the library, and so
hidden from the library user.
When the $HIDDEN list is present, those names listed
are not entered in the library XLIB name table. If
both $VISIBLE and $HIDDEN are present, only the
$HIDDEN list will be used.
$VARS Contains a list of variables that should remain RAM-
based, i.e., the stored objects are not included in
the library, and no XLIB name entries are made for
their names. All other variables in the source
directory names are included as library commands.
Multiple instances are permitted of the declaration variables
$VARS, $HIDDEN, and $VISIBLE variables, in various subdirectories
of the source directory. A particular variable is declared as a
RAM variable, hidden, etc., if its name is entered in any of the
-4-
relevant declaration variables anywhere in the current path
defined by the variable's location. That is, a variable XXX found
in any subdirectory will be hidden if XXX is in a list stored in
$HIDDEN in the top level of the source directory; but YYY in the
top level will not be hidden even if YYY is present in a $HIDDEN
list in a subdirectory.
Not all program objects that execute correctly from global
variables are directly convertible into libraries. In general, no
checks can be made for such errors, and USRLIB does not attempt to
do so. Here are some known pitfalls:
o+ Since a library cannot be modified, no library command may be
the target of a STO or PUT operation.
o+ XLIB names are not usable in all contexts in which global
names are valid arguments. This can cause constructs that
reference a named object to fail. For example,
'A' 5 GETI
where A is a list will not work when A is converted to an
XLIB name. Instead use
'A' EVAL 5 GETI
or better yet
A 5 GETI
XLIB names are not valid as formal variables in algebraics,
or as the independent variable for plotting or solving.
Names intended to be used as such should be declared as
global using $VARS or the -v option.
o+ ->STR applied to a global name that is converted to a
``hidden'' library command (see $HIDDEN) returns a null
string.
o+ Embedded directories (entered as DIR...END) within lists and
programs are not translated except for their first object.
-5-
1.3 Library Creation
The process of library creation and activation can be summarized
as follows.
1. Develop an application consisting of any number of programs
and other objects, and collect these in one single-level
directory in the HP 48.
2. Using Kermit binary transfer, send the directory to a PC.
3. Execute USRLIB, using the directory as the source file. In
this step, you also assign a library ID and a library title
to the output library.
4. Transfer the USRLIB output library object back to the HP 48,
to a variable in any convenient directory.
5. Recall the library object from the variable to which it was
transferred, and then store it in a RAM port (:n:x STO,
where n is the port number, and x is any number). After
storing the library, you can purge the original copy in the
variable to save memory.
6. Turn the HP 48 off, then on. This adds the new library to
the system library table, and gives the library a chance to
execute its own configuration program, if any. (The HP 48
will execute a system halt automatically at this stage, so
you should save any stack objects or PICT first if you wish
to recover them.) The LIBRARY menu will now contain a menu
entry labeled with the library's ID number in the PORTn
submenu.
7. Activate the directory in which you wish the library's
commands to be accessible, then execute nnn ATTACH, where
nnn is the library ID. Any number of libraries can be
attached to the HOME directory; subdirectories may have one
library attached to each. The main LIBRARY menu will now
contain a menu key labeled by the library's title.
To remove a library, activate its associated directory and execute
nnn DETACH. Then execute :n:ID PURGE to remove the library from
port n. (You will notice a brief jump in the display when you
execute the PURGE. This is normal and harmless.)
-6-
2. Instructions
(In the following, bbbboooolllldddd text represents user-supplied text. Text
appearing in brackets [ ] denotes optional entries. In actual
entries, the [ ] should not be used.)
Syntax:
USRLIB [-options] ddddiiiirrrrffffiiiilllleeee [ lllliiiibbbbffffiiiilllleeee [ ssssuuuummmmffffiiiilllleeee ] ]
ddddiiiirrrrffffiiiilllleeee is the name of the source file, which must contain a
binary image of an HP48 directory or a backup object
containing a directory.
LLLLiiiibbbbffffiiiilllleeee is a file to contain the output library object.
ssssuuuummmmffffiiiilllleeee This is a textual summary of the names that were
translated. The following information is given for each
object: user name, type, offset into the lllliiiibbbbffffiiiilllleeee file,
XLIB numbers, whether it can be used in an algebraic,
and whether it is visible.
Similarly, a list of message numbers and messages and a
summary of the space requirements is given.
SSSSuuuummmmffffiiiilllleeee and the optional lllliiiissssttttffffiiiilllleeee (see OPTIONS below) may be
redirected to stdout by using '-' for the output file name.
2.1 Options
The following options may be included in the USRLIB command line:
-dlllliiiissssttttffffiiiilllleeee lllliiiissssttttffffiiiilllleeee will contain a text listing of the contents
of each object in the input directory.
-hhhhheeeeaaaaddddeeeerrrr Use hhhheeeeaaaaddddeeeerrrr for the library object header (for file
transfer).
-llllliiiissssttttffffiiiilllleeee lllliiiissssttttffffiiiilllleeee will contain a text listing of the contents
of each object in the output library. Occurrances of
"ID'name'<--" indicate translation of an name (ID)
into an XLIB or a message table reference.
-rrrrroooommmmiiiidddd Set decimal Library ID (see $ROMID above).
-7-
-tttttiiiittttlllleeee Use ttttiiiittttlllleeee for the library title (see $TITLE above).
-vnnnnaaaammmmeeee Declare nnnnaaaammmmeeee as a RAM variable name (see $VARS above).
2.2 Restrictions
1. The total library output file cannot be larger than 128K
bytes.
2. Message strings must be less than 64K bytes each.
2.3 Example
The following example combines the programs PAD, PRESERVE, and a
modified version of BDISP from the Owner's Manual into a library
application.
The variables $TITLE, $ROMID, $VISIBLE, and $VARS control the
creation of the library. The variable $CONFIG contains a program
which attaches the library to the HOME directory whenever a System
Halt occurs.
BDISP has been modified to store the hex version of the input
number in the variable LSTN. The $VARS variable specifies that
LSTN will be a user variable (found in the VAR menu), and should
not be compiled into the library.
The programs PAD and PRESERVE are called by BDISP. Since the
control variable $VISIBLE only specifies BDISP, all other
variables are hidden (or left as globals as specified by the $VARS
variable).
-8-
In ASCII form, a directory containing everything required for the
complete library application looks like this:
%%HP: T(3)A(D)F(.);
DIR
PRESERVE
<< RCLF -> f
<< EVAL f STOF >>
>>
PAD
<< ->STR
WHILE
DUP SIZE 22 <
REPEAT
" " SWAP +
END
>>
BDISP
<<
<< DUP -55 CF
IFERR R->B
THEN
END -> n
<< CLLCD
<< BIN >>
<< OCT >>
<< DEC >>
<< HEX >>
1 4
FOR j
EVAL n ->STR PAD
j DISP
NEXT n 'LSTN' STO
>> 3 FREEZE
>> PRESERVE
>>
$CONFIG << HOME 800 ATTACH >>
$ROMID 800
$TITLE "BDLIB :Binary Display"
$VISIBLE { BDISP }
$VARS { LSTN }
END
-9-
2.4 Error Messages
In the following error messages, words shown in parentheses
represent values that indicate source-specific quantities. (path)
represents the path within the source directory to the variable
causing the error, in the form name1/name2/... , where the names
are the subdirectory names (on the HP 48SX, the path would be a
list { name1 name2 ... }).
"Insufficient Memory" - Memory is constantly being allocated
for various compiler needs.
"Unexpected EOF on Input" - EOF was found when more nibbles
were expected.
"USRLIB: Cannot open" - The source file can not be opened.
"USRLIB: - not legal for input" - "-" (stdin) can't be used
for input.
"ROMID must be in range 769 - 1792"
"Must have either -r romid or $ROMID" - No library ID was specified.
"Need either BAK of a directory or a directory"
"BAK object does not contain directory"
"Directory is empty"
"Object is not a string: (path)/$TITLE"
The next three messages may occur when ROMID is specified in the
variable $ROMID.
"Illegal Real value for (path)/$ROMID: (value)"
"Illegal Binary value for (path)/$ROMID: (value)"
"Object not Real or Binary: (path)/$ROMID"
The next two messages may occur when a $CONFIG variable (or two)
are specified.
"Object not program: (path)/$CONFIG"
"$CONFIG redefined: (path)/$CONFIG"
-10-
The next message may occur any time a string (variable name or
message) is read.
"Variable name or message too long (>65535)"
The next two messages may occur when a name list is being read. The
$MESSAGE, $VISIBLE, $HIDDEN, and $VARS variables are all name lists.
"Object is not a list: (path)/name"
"Non-ID found in list: (path)/name"
"Message object not found: (name)"
"Loss of object synchronism between passes: (path)/(name)"
- (path)/(name) is replaced with the object where out-of-sync
was discovered.
"Name must not exceed 16 characters: (path)/(name)"
- Library object names are limited to 16 characters.
"Keyword cannot resolve to a directory: (path)/(name)"
- Subdirectory names cannot be included in other directory
objects' definitions.
The next two messages may occur as message objects (indicated in the
$MESSAGE list) are being converted into a message table.
"Message object is not a string: (path)/(name)"
"Multiple definitions for message (path)/(name)"
The next three messages may occur as the final library object is being
written to the output file.
"Library image length is 0. LIB FILE NOT WRITTEN!"
"Max image size is 256K nibbles ... image is (value) nibbles.
LIB FILE NOT WRITTEN!"
"Unsucessful write to library file" - Unknown error writing to
library file.
-11-